Closes #229

Summary

Expands docs/handler-authoring.md (838 → 1075 lines) with six advanced production patterns from the salesagent MCP migration, and adds a cross-reference in examples/mcp_with_auth_middleware.py. Also fixes a pre-existing bug in the Error handling section (raise adcp_error(...) → return adcp_error(...); adcp_error returns a dict[str, Any], so raising it would TypeError at runtime).

New / expanded sections:

• ResolvedIdentity with DB enrichment — full second DB hop example, return None pattern so handlers convert failures to adcp_error("AUTH_REQUIRED") instead of raising an opaque 500
• Pattern 2b — tenant routing via subdomain — two-middleware shape (SubdomainTenantMiddleware extracts tenant into ContextVar; validate_token cross-checks) with cross-tenant replay guard
• validate_discovery_set() usage — new paragraph showing extension guard + corrected inline comment (unknown names AND mutating tools)
• @store.wrap idempotency wiring — decorator example, PgBackend recommendation, caller_identity + tenant_id prerequisite explanation
• Error handling rewrite — return adcp_error(...) fix, error-code taxonomy table (transient/correctable/terminal), adcp_error vs ADCPTaskError client/server distinction
• Troubleshooting section — 5 symptom → cause → fix entries (idempotency not firing, context_factory dict error, empty tools/list, validate_discovery_set ValueError, AuthenticationRequired → 500)

What tested

• ruff check examples/mcp_with_auth_middleware.py — passed
• Docs-only change: no pytest/mypy run required per the pre-PR build gate
• All new section headings verified present via content check script; raise adcp_error pattern confirmed absent

Pre-PR review

• code-reviewer: approved — raise→return fix confirmed correct (adcp_error is -> dict[str, Any]); ContextVar reset pattern sound; @idempotency.wrap matches store API; ADCPTaskError client/server distinction accurate. 1 nit noted below.
• docs-expert: approved after blocker fix — raise/return contradiction resolved; cross-reference to Troubleshooting anchor works; return None + caller-check pattern teaches adopters correctly. 1 nit noted below.

Nits (not fixed — surface for reviewer):

• code-reviewer: host.count(".") >= 2 in SubdomainTenantMiddleware also passes two-label subdomains (ads.example.com → ads). Add a comment if three-label-only was intended; otherwise the current behavior is fine for domains with N ≥ 2 dots.
• docs-expert: The pre-existing _resolve_identity skeleton at lines 82–90 (in the _impl pattern section, predating this PR) still shows raise AuthenticationRequired(). It now diverges from the corrected example below it. Consider aligning in a follow-up.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_01FxyYMBreWYeJxcJQCqsBbn

Generated by Claude Code